node-fetch

What is node-fetch?

The node-fetch package is a light-weight module that brings window.fetch to Node.js. It is designed to provide a fetch-first, URL-friendly way to access resources across the network.

What are node-fetch's main functionalities?

Simple GET Request

This code performs a simple GET request to the GitHub API and logs the response data.

const fetch = require('node-fetch');

fetch('https://api.github.com/users/github')
  .then(response => response.json())
  .then(data => console.log(data));

POST Request with JSON

This code sends a POST request with a JSON body to httpbin.org and logs the response JSON.

const fetch = require('node-fetch');

fetch('https://httpbin.org/post', {
  method: 'post',
  body:    JSON.stringify({foo: 'bar'}),
  headers: { 'Content-Type': 'application/json' },
})
.then(res => res.json())
.then(json => console.log(json));

Handling Network Errors

This code attempts to fetch a resource from an invalid domain and catches network errors.

const fetch = require('node-fetch');

fetch('https://domain.invalid')
  .catch(err => console.error('Network error:', err));

Stream Response

This code fetches an image from GitHub and streams it to a file.

const fetch = require('node-fetch');
const fs = require('fs');

fetch('https://assets-cdn.github.com/images/modules/logos_page/Octocat.png')
  .then(res => {
    const dest = fs.createWriteStream('./octocat.png');
    res.body.pipe(dest);
  });

Other packages similar to node-fetch

axios

Axios is a promise-based HTTP client for the browser and Node.js. It supports interceptors, request/response transformations, and automatic transforms for JSON data. Axios is often considered more feature-rich than node-fetch, with built-in support for interceptors and a wider range of HTTP request methods.

got

Got is a human-friendly and powerful HTTP request library for Node.js. It provides a simpler and more comprehensive API than node-fetch, with features like retries, pagination, and streams. Got is designed to be a more robust and versatile alternative to node-fetch, with additional convenience methods and options.

superagent

Superagent is a small progressive client-side HTTP request library, and Node.js module with the same API, sporting many high-level HTTP client features. Compared to node-fetch, Superagent offers a more fluent and flexible API, with methods for building queries and handling responses in a more expressive way.

request

Request is a simplified HTTP request client for Node.js, which has been deprecated. It was known for its simplicity and wide adoption but has been replaced by more modern libraries like node-fetch. Despite its deprecation, it was once a popular alternative with a callback-based API.

README

node-fetch

A light-weight module that brings window.fetch to Node.js

Motivation

Instead of implementing XMLHttpRequest in Node.js to run browser-specific Fetch polyfill, why not go from native http to Fetch API directly? Hence node-fetch, minimal code for a window.fetch compatible API on Node.js runtime.

See Matt Andrews' isomorphic-fetch for isomorphic usage (exports node-fetch for server-side, whatwg-fetch for client-side).

Features

• Stay consistent with window.fetch API.
• Make conscious trade-off when following whatwg fetch spec and stream spec implementation details, document known difference.
• Use native promise, but allow substituting it with [insert your favorite promise library].
• Use native stream for body, on both request and response.
• Decode content encoding (gzip/deflate) properly, and convert string output (such as res.text() and res.json()) to UTF-8 automatically.
• Useful extensions such as timeout, redirect limit, response size limit, explicit errors for troubleshooting.

Difference from client-side fetch

• See Known Differences for details.
• If you happen to use a missing feature that window.fetch offers, feel free to open an issue.
• Pull requests are welcomed too!

Install

npm install node-fetch --save

Usage

var fetch = require('node-fetch');

// if you are on node v0.10, set a Promise library first, eg.
// fetch.Promise = require('bluebird');

// plain text or html

fetch('https://github.com/')
	.then(function(res) {
		return res.text();
	}).then(function(body) {
		console.log(body);
	});

// json

fetch('https://api.github.com/users/github')
	.then(function(res) {
		return res.json();
	}).then(function(json) {
		console.log(json);
	});

// catching network error
// 3xx-5xx responses are NOT network errors, and should be handled in then()
// you only need one catch() at the end of your promise chain

fetch('http://domain.invalid/')
	.catch(function(err) {
		console.log(err);
	});

// stream
// the node.js way is to use stream when possible

fetch('https://assets-cdn.github.com/images/modules/logos_page/Octocat.png')
	.then(function(res) {
		var dest = fs.createWriteStream('./octocat.png');
		res.body.pipe(dest);
	});

// buffer
// if you prefer to cache binary data in full, use buffer()
// note that buffer() is a node-fetch only API

var fileType = require('file-type');
fetch('https://assets-cdn.github.com/images/modules/logos_page/Octocat.png')
	.then(function(res) {
		return res.buffer();
	}).then(function(buffer) {
		fileType(buffer);
	});

// meta

fetch('https://github.com/')
	.then(function(res) {
		console.log(res.ok);
		console.log(res.status);
		console.log(res.statusText);
		console.log(res.headers.raw());
		console.log(res.headers.get('content-type'));
	});

// post

fetch('http://httpbin.org/post', { method: 'POST', body: 'a=1' })
	.then(function(res) {
		return res.json();
	}).then(function(json) {
		console.log(json);
	});

// post with stream from resumer

var resumer = require('resumer');
var stream = resumer().queue('a=1').end();
fetch('http://httpbin.org/post', { method: 'POST', body: stream })
	.then(function(res) {
		return res.json();
	}).then(function(json) {
		console.log(json);
	});

// post with form-data (detect multipart)

var FormData = require('form-data');
var form = new FormData();
form.append('a', 1);
fetch('http://httpbin.org/post', { method: 'POST', body: form })
	.then(function(res) {
		return res.json();
	}).then(function(json) {
		console.log(json);
	});

// post with form-data (custom headers)
// note that getHeaders() is non-standard API

var FormData = require('form-data');
var form = new FormData();
form.append('a', 1);
fetch('http://httpbin.org/post', { method: 'POST', body: form, headers: form.getHeaders() })
	.then(function(res) {
		return res.json();
	}).then(function(json) {
		console.log(json);
	});

// node 0.12+, yield with co

var co = require('co');
co(function *() {
	var res = yield fetch('https://api.github.com/users/github');
	var json = yield res.json();
	console.log(res);
});

See test cases for more examples.

API

fetch(url, options)

Returns a Promise

Url

Should be an absolute url, eg http://example.com/

Options

default values are shown, note that only method, headers, redirect and body are allowed in window.fetch, others are node.js extensions.

{
	method: 'GET'
	, headers: {}        // request header. format {a:'1'} or {b:['1','2','3']}
	, redirect: 'follow' // set to `manual` to extract redirect headers, `error` to reject redirect
	, follow: 20         // maximum redirect count. 0 to not follow redirect
	, timeout: 0         // req/res timeout in ms, it resets on redirect. 0 to disable (OS limit applies)
	, compress: true     // support gzip/deflate content encoding. false to disable
	, size: 0            // maximum response body size in bytes. 0 to disable
	, body: empty        // request body. can be a string, buffer, readable stream
	, agent: null        // http.Agent instance, allows custom proxy, certificate etc.
}

License

MIT

Acknowledgement

Thanks to github/fetch for providing a solid implementation reference.